When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

Walkthrough

This change refactors credit-related schemas and types across identities and keys in the OpenAPI specification and generated Go code. It introduces consolidated types (CreditInterval, CreditOperation, Credits, UpdateCredits, VerifyKeyIdentity) replacing key-specific variants, and integrates credits handling at both identity and key levels with new endpoints and modified request/response structures.

Changes

Sequence Diagram

sequenceDiagram
    participant Client
    participant API
    participant Handler
    
    rect rgb(200, 220, 255)
    Note over Client,Handler: Identity-Level Credits Update (new)
    Client->>API: POST /v2/identities.updateCredits<br/>(identity, operation, value)
    API->>Handler: updateIdentityCredits<br/>(CreditOperation: set|increment|decrement)
    Handler->>Handler: Apply operation to identity credits<br/>(value or null for unlimited)
    Handler-->>API: Credits updated<br/>(remaining, refill)
    API-->>Client: 200 OK<br/>V2IdentitiesUpdateCreditsResponseBody
    end

    rect rgb(220, 200, 255)
    Note over Client,Handler: Key-Level Credits Update (refactored)
    Client->>API: PATCH /v2/keys/{keyId}/updateCredits<br/>(operation, value)
    API->>Handler: updateKeyCredits<br/>(CreditOperation: set|increment|decrement)
    Handler->>Handler: Apply operation to key credits<br/>(or identity-level credits if prioritized)
    Handler-->>API: Credits updated<br/>(Credits type)
    API-->>Client: 200 OK<br/>V2KeysUpdateCreditsResponseBody
    end

    rect rgb(200, 255, 220)
    Note over Client,Handler: Key Verification (identity shape refined)
    Client->>API: GET /v2/keys/{key}/verify
    API->>Handler: verifyKey
    Handler->>Handler: Validate key & retrieve identity
    Handler-->>API: VerifyKeyIdentity<br/>(id, externalId, meta, ratelimits)
    API-->>Client: 200 OK<br/>V2KeysVerifyKeyResponseData<br/>(includes VerifyKeyIdentity)
    end

Estimated code review effort

🎯 4 (Complex) | ⏱️ ~45 minutes

Areas requiring extra attention:

• Cross-references consistency: Verify all $ref updates from KeyCreditsData → Credits and UpdateKeyCreditsData → UpdateCredits are complete and correct across all endpoint definitions
• Nullability semantics: Confirm null behavior for unlimited credits and disabled refills is correctly expressed in UpdateCredits and UpdateCreditsRefill schemas
• Identity vs. key credit precedence: Validate that identity-level credits properly override key-level credits in implementation logic and documentation
• New VerifyKeyIdentity type: Ensure all fields (id, externalId, meta, ratelimits) align with Identity schema expectations and don't break downstream consumers
• CreditOperation enum usage: Confirm set/increment/decrement operations are correctly applied across both identity and key endpoints
• Endpoint operation naming: Verify updateKeyCredits (renamed from updateCredits) doesn't conflict with identity's updateIdentityCredits operationId

Possibly related PRs

• feat: v2/keys.updateCredits #3443: Modifies V2KeysUpdateCredits types and credit operation enum values—directly overlaps with this PR's key-level credit update surface changes.
• fix: use simplified queries for key decrements #3804: Refactors key-credits update flow handling and operation type—related to credit operation enum and request/response restructuring.
• feat: v2/keys.getKey #3421: Introduces Credits, Refill, and VerifyKeyIdentity schema changes—foundational changes extended by this PR's consolidated credit types and identity verification.

Suggested labels

Core Team

• X
• Mastodon
• Reddit
• LinkedIn

1 gif was posted to this PR based on Andreas Thomas's automation.